Read remote files: client.file(path) with byte ranges, streaming and digests (#146) - #177

Closes #146 — first issue of the remote file access family (#146 → #145 listing, #147 download, #148 CLI).

What

byte[] content = client.file("C:\\Windows\\Temp\\collect.bin").readBytes();
String tail = client.file("D:\\logs\\huge.log").offset(-8192).readText(StandardCharsets.UTF_8);
try (InputStream in = client.file(path).openStream()) { ... }   // bounded memory, no cap
String sha = client.file(path).digest("SHA256");

• WinRMClient.file(path) → RemoteFile request: offset(long) (negative = from the end, resolved on the host from the open stream), length(long), maxBytes(long) (64 MiB default cap for the in-memory terminals, also sent to the host), timeout(Duration).
• Package-private RemoteFiles primitive: a PowerShell script (-EncodedCommand, path embedded base64-encoded: no quoting) opens the file with a ReadWrite share mode (logs held open by a service can be read), seeks, and writes each block as one base64 line to the raw stdout stream. The client decodes lines as they arrive; the exit code, checked at the end of the output, becomes an explicit WinRMClientException (not found, directory, access denied, sharing violation, Constrained Language Mode, PowerShell missing). A missing file fails in openStream() itself; a failure midway is never a silently short read.
• Docs: new files.md page (menu, index, cross-link from file-transfers.md), README one-liner.

Performance

Investigated in depth: the WinRM service reads a command's stdout pipe itself, at most 32 KiB per read, ~60 reads/s per stream — not CPU (host 97–99 % idle; client ingests 24–31 MB/s). Blocks are therefore 49,149 bytes, so each 65,533-byte line fills exactly two reads. Measured with a 20 MiB file, SHA-256 verified:

Follow-ups opened from these measurements: #175 (raw bytes instead of base64, ~+33 %) and #176 (parallel ranged downloads, ~3× with 4 connections).

Tests

• RemoteFilesScriptTest runs the generated scripts in the local powershell.exe (Windows only, skipped elsewhere): every byte value across blocks, non-ASCII name, ranges, negative offsets, a file held open by a writer, a locked file → sharing violation, exit codes, digest.
• RemoteFileTest (FakeWsmanServer): base64 lines split across Receive chunks, a UTF-8 character split across blocks, BOM kept, size cap sent and enforced, failures, unexpected output, wall-clock timeout.
• WinRMLiveTest: byte-exact read of a non-ASCII-named file, tail range, digest; 1 GiB tail served by a seek; a file held open for writing by another session. Passed on anaxagore (2008 R2) and tc-win2022.
• mvn clean verify site green: no checkstyle/PMD/SpotBugs findings.

Deviations from the issue

• readText(Charset) / openReader(Charset) take the charset as a parameter (no charset() setter, no default to forget).
• digest() hashes with .NET on the host, reusing the same script and exit-code mapping, rather than ShellFileCopy's certutil probe (which goes through cmd.exe quoting).

🤖 Generated with Claude Code